docs: update README and .env.example with new download structure

- Reorganize downloads into downloads/{permanent,cache,kept}
- Update Spotify Import configuration (keep sync window settings)
- Expand Jellyfin API endpoints documentation (primary focus)
- Move Jellyfin backend section before Subsonic
- Simplify Spotify Import documentation
- Add all manual API trigger endpoints
- Update download folder structure diagram
- Add MIGRATION.md guide for existing installations

.env.example

@@ -35,15 +35,13 @@ JELLYFIN_LIBRARY_ID=
 # Music service to use: SquidWTF, Deezer, or Qobuz (default: SquidWTF)
 MUSIC_SERVICE=SquidWTF
 
-# Path where downloaded songs will be stored on the host (only applies if STORAGE_MODE=Permanent)
+# Base directory for all downloads (default: ./downloads)
+# This creates three subdirectories:
+# - downloads/permanent/ - Permanently downloaded tracks (STORAGE_MODE=Permanent)
+# - downloads/cache/ - Temporarily cached tracks (STORAGE_MODE=Cache)
+# - downloads/kept/ - Favorited external tracks (always permanent)
 DOWNLOAD_PATH=./downloads
 
-# Path where favorited external tracks are permanently kept
-KEPT_PATH=./kept
-
-# Path for cache files (Spotify missing tracks, etc.)
-CACHE_PATH=./cache
-
 # ===== SQUIDWTF CONFIGURATION =====
 # Different quality options for SquidWTF. Only FLAC supported right now
 SQUIDWTF_QUALITY=FLAC
@@ -112,27 +110,26 @@ CACHE_DURATION_HOURS=1
 
 # ===== SPOTIFY PLAYLIST INJECTION (JELLYFIN ONLY) =====
 # REQUIRES: Jellyfin Spotify Import Plugin (https://github.com/Viperinius/jellyfin-plugin-spotify-import)
-# This feature intercepts Spotify Import plugin playlists (Release Radar, Discover Weekly) and fills them
-# with tracks auto-matched from external providers (SquidWTF, Deezer, Qobuz)
+# This feature intercepts Spotify Import plugin playlists and fills them with tracks from external providers
 # Uses JELLYFIN_URL and JELLYFIN_API_KEY configured above (no separate credentials needed)
 
 # Enable Spotify playlist injection (optional, default: false)
 SPOTIFY_IMPORT_ENABLED=false
 
 # Sync schedule: When does the Spotify Import plugin run?
+# Used for the sync window check to avoid fetching too frequently
 # Set these to match your plugin's sync schedule in Jellyfin
 # Example: If plugin runs daily at 4:15 PM, set HOUR=16 and MINUTE=15
 SPOTIFY_IMPORT_SYNC_START_HOUR=16
 SPOTIFY_IMPORT_SYNC_START_MINUTE=15
 
 # Sync window: How long to search for missing tracks files (in hours)
-# The fetcher will check every 5 minutes within this window
-# Example: If plugin runs at 4:15 PM and window is 2 hours, checks from 4:00 PM to 6:00 PM
+# The fetcher will check within this window after the sync start time
+# Example: If plugin runs at 4:15 PM and window is 2 hours, checks from 4:15 PM to 6:15 PM
 SPOTIFY_IMPORT_SYNC_WINDOW_HOURS=2
 
 # Matching interval: How often to run track matching (in hours)
 # Spotify playlists like Discover Weekly update once per week, Release Radar updates weekly
-# Most playlists don't change frequently, so running once per day is reasonable
 # Set to 0 to only run once on startup (manual trigger via admin UI still works)
 # Default: 24 hours
 SPOTIFY_IMPORT_MATCHING_INTERVAL_HOURS=24