Implement external calendar integration and enhance API functionality

- Added support for fetching and parsing external ICS calendars, allowing events to be displayed on the duty grid.
- Introduced a new API endpoint `/api/calendar-events` to retrieve calendar events within a specified date range.
- Updated configuration to include `EXTERNAL_CALENDAR_ICS_URL` for specifying the ICS calendar URL.
- Enhanced the web application to visually indicate days with events and provide event summaries on hover.
- Improved documentation in the README to include details about the new calendar integration and configuration options.
- Updated tests to cover the new calendar functionality and ensure proper integration.

db/repository.py

@@ -40,7 +40,12 @@ def get_duties(
     from_date: str,
     to_date: str,
 ) -> list[tuple[Duty, str]]:
-    """Return list of (Duty, full_name) overlapping the given date range (ISO date strings)."""
+    """Return list of (Duty, full_name) overlapping the given date range.
+
+    from_date/to_date are YYYY-MM-DD (first/last day of month in client's local calendar).
+    Duty.start_at and end_at are stored in UTC (ISO 8601 with Z); lexicographic comparison
+    with date strings yields correct overlap.
+    """
     q = (
         session.query(Duty, User.full_name)
         .join(User, Duty.user_id == User.id)
@@ -55,6 +60,7 @@ def insert_duty(
     start_at: str,
     end_at: str,
 ) -> Duty:
+    """Create a duty. start_at and end_at must be UTC, ISO 8601 with Z (e.g. 2025-01-15T09:00:00Z)."""
     duty = Duty(user_id=user_id, start_at=start_at, end_at=end_at)
     session.add(duty)
     session.commit()