Task 4.2: Update Download API Endpoints to Use Key

- Updated DownloadRequest and DownloadItem models with comprehensive
  docstrings explaining serie_id (key as primary identifier) vs
  serie_folder (filesystem metadata)
- Updated add_to_queue() endpoint docstring to document request parameters
- Updated all test files to include required serie_folder field:
  - tests/api/test_download_endpoints.py
  - tests/api/test_queue_features.py
  - tests/frontend/test_existing_ui_integration.py
  - tests/integration/test_download_flow.py
- Updated infrastructure.md with Download Queue request/response models
- All 869 tests pass

This is part of the Series Identifier Standardization effort (Phase 4.2)
to ensure key is used as the primary identifier throughout the codebase.

src/server/api/download.py

@@ -74,7 +74,12 @@ async def add_to_queue(
     Requires authentication.
 
     Args:
-        request: Download request with serie info, episodes, and priority
+        request: Download request containing:
+            - serie_id: Series key (primary identifier, 'attack-on-titan')
+            - serie_folder: Filesystem folder name for storing downloads
+            - serie_name: Display name for the series
+            - episodes: List of episodes to download
+            - priority: Queue priority level
 
     Returns:
         DownloadResponse: Status and list of created download item IDs

src/server/models/download.py

@@ -63,24 +63,33 @@ class DownloadProgress(BaseModel):
 
 
 class DownloadItem(BaseModel):
-    """Represents a single download item in the queue."""
+    """Represents a single download item in the queue.
+    
+    Note on identifiers:
+    - serie_id: The provider-assigned key (e.g., 'attack-on-titan') used for
+      all lookups and identification. This is the primary identifier.
+    - serie_folder: The filesystem folder name (e.g., 'Attack on Titan (2013)')
+      used only for filesystem operations. This is metadata, not an identifier.
+    """
 
     id: str = Field(..., description="Unique download item identifier")
     serie_id: str = Field(
         ...,
         description=(
-            "Series identifier - provider key "
-            "(e.g., 'attack-on-titan')"
+            "Series key (primary identifier) - provider-assigned URL-safe "
+            "key (e.g., 'attack-on-titan'). Used for lookups/identification."
         )
     )
     serie_folder: str = Field(
         ...,
         description=(
-            "Series folder name on disk "
-            "(e.g., 'Attack on Titan (2013)')"
+            "Series folder name on disk (metadata only) "
+            "(e.g., 'Attack on Titan (2013)'). For filesystem ops only."
         )
     )
-    serie_name: str = Field(..., min_length=1, description="Series name")
+    serie_name: str = Field(
+        ..., min_length=1, description="Series display name"
+    )
     episode: EpisodeIdentifier = Field(
         ..., description="Episode identification"
     )
@@ -168,24 +177,31 @@ class QueueStats(BaseModel):
 
 
 class DownloadRequest(BaseModel):
-    """Request to add episode(s) to the download queue."""
+    """Request to add episode(s) to the download queue.
+    
+    Note on identifiers:
+    - serie_id: The provider-assigned key (e.g., 'attack-on-titan') used as
+      the primary identifier for all operations. This is the unique key.
+    - serie_folder: The filesystem folder name (e.g., 'Attack on Titan (2013)')
+      used only for storing downloaded files. This is metadata.
+    """
 
     serie_id: str = Field(
         ...,
         description=(
-            "Series identifier - provider key "
-            "(e.g., 'attack-on-titan')"
+            "Series key (primary identifier) - provider-assigned URL-safe "
+            "key (e.g., 'attack-on-titan'). Used for lookups/identification."
         )
     )
     serie_folder: str = Field(
         ...,
         description=(
-            "Series folder name on disk "
-            "(e.g., 'Attack on Titan (2013)')"
+            "Series folder name on disk (metadata only) "
+            "(e.g., 'Attack on Titan (2013)'). For filesystem ops only."
         )
     )
     serie_name: str = Field(
-        ..., min_length=1, description="Series name for display"
+        ..., min_length=1, description="Series display name"
     )
     episodes: List[EpisodeIdentifier] = Field(
         ..., description="List of episodes to download"