Task 4.4: Update WebSocket API Endpoints to use key identifier

- Updated src/server/api/websocket.py docstrings to document key as primary series identifier
- Updated src/server/models/websocket.py with detailed docstrings explaining key and folder fields in message payloads
- Updated src/server/services/websocket_service.py broadcast method docstrings to document key field usage
- Added WebSocket message example with key in infrastructure.md
- All 83 WebSocket tests pass
- Task 4.4 marked as complete in instructions.md

src/server/models/websocket.py

@@ -3,6 +3,15 @@
 This module defines message models for WebSocket communication between
 the server and clients. Models ensure type safety and provide validation
 for real-time updates.
+
+Series Identifier Convention:
+    - `key`: Primary identifier for series (provider-assigned, URL-safe)
+             e.g., "attack-on-titan"
+    - `folder`: Display metadata only (e.g., "Attack on Titan (2013)")
+    
+All series-related WebSocket events should include `key` as the primary
+identifier in their data payload. The `folder` field is optional and
+used for display purposes only.
 """
 from __future__ import annotations
 
@@ -65,7 +74,16 @@ class WebSocketMessage(BaseModel):
 
 
 class DownloadProgressMessage(BaseModel):
-    """Download progress update message."""
+    """Download progress update message.
+    
+    Data payload should include:
+        - download_id: Unique download identifier
+        - key: Series identifier (primary, e.g., 'attack-on-titan')
+        - folder: Series folder name (optional, display only)
+        - percent: Download progress percentage
+        - speed_mbps: Download speed
+        - eta_seconds: Estimated time remaining
+    """
 
     type: WebSocketMessageType = Field(
         default=WebSocketMessageType.DOWNLOAD_PROGRESS,
@@ -77,12 +95,22 @@ class DownloadProgressMessage(BaseModel):
     )
     data: Dict[str, Any] = Field(
         ...,
-        description="Progress data including download_id, percent, speed, eta",
+        description=(
+            "Progress data including download_id, key (series identifier), "
+            "folder (display), percent, speed_mbps, eta_seconds"
+        ),
     )
 
 
 class DownloadCompleteMessage(BaseModel):
-    """Download completion message."""
+    """Download completion message.
+    
+    Data payload should include:
+        - download_id: Unique download identifier
+        - key: Series identifier (primary, e.g., 'attack-on-titan')
+        - folder: Series folder name (optional, display only)
+        - file_path: Path to downloaded file
+    """
 
     type: WebSocketMessageType = Field(
         default=WebSocketMessageType.DOWNLOAD_COMPLETE,
@@ -93,12 +121,23 @@ class DownloadCompleteMessage(BaseModel):
         description="ISO 8601 timestamp",
     )
     data: Dict[str, Any] = Field(
-        ..., description="Completion data including download_id, file_path"
+        ...,
+        description=(
+            "Completion data including download_id, key (series identifier), "
+            "folder (display), file_path"
+        ),
     )
 
 
 class DownloadFailedMessage(BaseModel):
-    """Download failure message."""
+    """Download failure message.
+    
+    Data payload should include:
+        - download_id: Unique download identifier
+        - key: Series identifier (primary, e.g., 'attack-on-titan')
+        - folder: Series folder name (optional, display only)
+        - error_message: Description of the failure
+    """
 
     type: WebSocketMessageType = Field(
         default=WebSocketMessageType.DOWNLOAD_FAILED,
@@ -109,7 +148,11 @@ class DownloadFailedMessage(BaseModel):
         description="ISO 8601 timestamp",
     )
     data: Dict[str, Any] = Field(
-        ..., description="Error data including download_id, error_message"
+        ...,
+        description=(
+            "Error data including download_id, key (series identifier), "
+            "folder (display), error_message"
+        ),
     )