feat: Enhanced anime add flow with sanitized folders and targeted scan

- Add sanitize_folder_name utility for filesystem-safe folder names
- Add sanitized_folder property to Serie entity
- Update SerieList.add() to use sanitized display names for folders
- Add scan_single_series() method for targeted episode scanning
- Enhance add_series endpoint: DB save -> folder create -> targeted scan
- Update response to include missing_episodes and total_missing
- Add comprehensive unit tests for new functionality
- Update API tests with proper mock support

src/core/entities/series.py

@@ -1,6 +1,8 @@
 import json
 import warnings
 
+from src.server.utils.filesystem import sanitize_folder_name
+
 
 class Serie:
     """
@@ -127,6 +129,35 @@ class Serie:
     def episodeDict(self, value: dict[int, list[int]]):
         self._episodeDict = value
 
+    @property
+    def sanitized_folder(self) -> str:
+        """
+        Get a filesystem-safe folder name derived from the display name.
+        
+        This property returns a sanitized version of the series name
+        suitable for use as a filesystem folder name. It removes/replaces
+        characters that are invalid for filesystems while preserving
+        Unicode characters.
+        
+        Use this property when creating folders for the series on disk.
+        The `folder` property stores the actual folder name used.
+        
+        Returns:
+            str: Filesystem-safe folder name based on display name
+            
+        Example:
+            >>> serie = Serie("attack-on-titan", "Attack on Titan: Final", ...)
+            >>> serie.sanitized_folder
+            'Attack on Titan Final'
+        """
+        # Use name if available, fall back to folder, then key
+        name_to_sanitize = self._name or self._folder or self._key
+        try:
+            return sanitize_folder_name(name_to_sanitize)
+        except ValueError:
+            # Fallback to key if name cannot be sanitized
+            return sanitize_folder_name(self._key)
+
     def to_dict(self):
         """Convert Serie object to dictionary for JSON serialization."""
         return {