Phase 6: Update database layer identifier documentation

- Updated AnimeSeries model docstring to clarify key is primary identifier
- Updated folder field to indicate metadata-only usage
- Updated AnimeSeriesService docstring and get_by_key method
- Updated infrastructure.md with database identifier documentation
- All 996 tests passing

src/server/database/models.py

@@ -38,20 +38,31 @@ class AnimeSeries(Base, TimestampMixin):
     Represents an anime series with metadata, provider information,
     and links to episodes. Corresponds to the core Serie class.
     
+    Series Identifier Convention:
+        - `key`: PRIMARY IDENTIFIER - Unique, provider-assigned, URL-safe
+          (e.g., "attack-on-titan"). Used for all lookups and operations.
+        - `folder`: METADATA ONLY - Filesystem folder name for display
+          (e.g., "Attack on Titan (2013)"). Never used for identification.
+        - `id`: Internal database primary key for relationships.
+    
     Attributes:
-        id: Primary key
-        key: Unique identifier used by provider
-        name: Series name
+        id: Database primary key (internal use for relationships)
+        key: Unique provider key - PRIMARY IDENTIFIER for all lookups
+        name: Display name of the series
         site: Provider site URL
-        folder: Local filesystem path
+        folder: Filesystem folder name (metadata only, not for lookups)
         description: Optional series description
         status: Current status (ongoing, completed, etc.)
         total_episodes: Total number of episodes
         cover_url: URL to series cover image
-        episodes: Relationship to Episode models
-        download_items: Relationship to DownloadQueueItem models
+        episodes: Relationship to Episode models (via id foreign key)
+        download_items: Relationship to DownloadQueueItem models (via id foreign key)
         created_at: Creation timestamp (from TimestampMixin)
         updated_at: Last update timestamp (from TimestampMixin)
+    
+    Note:
+        All database relationships use `id` (primary key), not `key` or `folder`.
+        Use `get_by_key()` in AnimeSeriesService for lookups.
     """
     __tablename__ = "anime_series"
     
@@ -63,7 +74,7 @@ class AnimeSeries(Base, TimestampMixin):
     # Core identification
     key: Mapped[str] = mapped_column(
         String(255), unique=True, nullable=False, index=True,
-        doc="Unique provider key"
+        doc="Unique provider key - PRIMARY IDENTIFIER for all lookups"
     )
     name: Mapped[str] = mapped_column(
         String(500), nullable=False, index=True,
@@ -75,7 +86,7 @@ class AnimeSeries(Base, TimestampMixin):
     )
     folder: Mapped[str] = mapped_column(
         String(1000), nullable=False,
-        doc="Local filesystem path"
+        doc="Filesystem folder name - METADATA ONLY, not for lookups"
     )
     
     # Metadata