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

MIGRATION.md

@@ -0,0 +1,157 @@
+# Migration Guide: Reorganizing Download Structure
+
+This guide is for upgrading from the old download structure to the new unified structure.
+
+## Old Structure
+```
+./downloads/     # Permanent downloads
+./kept/          # Favorited tracks  
+./cache/         # Cached tracks
+```
+
+## New Structure
+```
+./downloads/
+├── permanent/   # Permanent downloads
+├── kept/        # Favorited tracks
+└── cache/       # Cached tracks
+```
+
+## Migration Steps
+
+### 1. Stop the Container
+```bash
+docker-compose down
+```
+
+### 2. Backup Your Data (Recommended)
+```bash
+# Create a backup
+tar -czf allstarr-backup-$(date +%Y%m%d).tar.gz downloads/ kept/ cache/ 2>/dev/null
+```
+
+### 3. Create New Directory Structure
+```bash
+mkdir -p downloads/permanent downloads/kept downloads/cache
+```
+
+### 4. Move Existing Files
+
+**Move permanent downloads:**
+```bash
+# If you have files directly in downloads/
+if [ -d "downloads" ] && [ ! -d "downloads/permanent" ]; then
+  # Move all files/folders except the new subdirectories
+  find downloads/ -maxdepth 1 -mindepth 1 ! -name 'permanent' ! -name 'kept' ! -name 'cache' ! -name 'playlists' -exec mv {} downloads/permanent/ \;
+fi
+
+# Move playlists folder if it exists
+if [ -d "downloads/playlists" ]; then
+  mv downloads/playlists downloads/permanent/
+fi
+```
+
+**Move kept files:**
+```bash
+if [ -d "kept" ]; then
+  mv kept/* downloads/kept/ 2>/dev/null || true
+  rmdir kept
+fi
+```
+
+**Move cache files:**
+```bash
+if [ -d "cache" ]; then
+  mv cache/* downloads/cache/ 2>/dev/null || true
+  rmdir cache
+fi
+```
+
+### 5. Update .env File
+```bash
+# Remove old variables
+sed -i.bak '/^KEPT_PATH=/d' .env
+sed -i.bak '/^CACHE_PATH=/d' .env
+
+# Ensure DOWNLOAD_PATH is set correctly
+if ! grep -q "^DOWNLOAD_PATH=" .env; then
+  echo "DOWNLOAD_PATH=./downloads" >> .env
+else
+  sed -i.bak 's|^DOWNLOAD_PATH=.*|DOWNLOAD_PATH=./downloads|' .env
+fi
+```
+
+### 6. Update Media Server Library Paths
+
+**For Jellyfin:**
+1. Go to Dashboard → Libraries
+2. Edit your Music library
+3. Update the folder path from `downloads` to `downloads/permanent`
+4. Scan library
+
+**For Navidrome/Subsonic:**
+1. Update your music folder configuration
+2. Change from `downloads` to `downloads/permanent`
+3. Restart and rescan
+
+### 7. Verify Migration
+```bash
+# Check the new structure
+ls -la downloads/
+ls -la downloads/permanent/
+ls -la downloads/kept/
+ls -la downloads/cache/
+
+# Count files in each directory
+echo "Permanent: $(find downloads/permanent -type f | wc -l) files"
+echo "Kept: $(find downloads/kept -type f | wc -l) files"
+echo "Cache: $(find downloads/cache -type f | wc -l) files"
+```
+
+### 8. Start the Container
+```bash
+docker-compose up -d
+```
+
+### 9. Check Logs
+```bash
+docker-compose logs -f allstarr
+```
+
+## Rollback (If Needed)
+
+If something goes wrong:
+
+```bash
+# Stop container
+docker-compose down
+
+# Restore from backup
+tar -xzf allstarr-backup-YYYYMMDD.tar.gz
+
+# Restore old .env
+mv .env.bak .env
+
+# Start container
+docker-compose up -d
+```
+
+## Verification Checklist
+
+- [ ] All files moved to new structure
+- [ ] Old directories removed or empty
+- [ ] .env file updated
+- [ ] Media server library paths updated
+- [ ] Container starts without errors
+- [ ] Can play existing tracks
+- [ ] New downloads go to correct folders
+- [ ] Favoriting external tracks works
+- [ ] Cache cleanup works
+
+## Notes
+
+- The migration preserves all your existing files
+- Playlists (.m3u files) are moved to `downloads/permanent/playlists/`
+- Relative paths in M3U files should still work
+- If you have a lot of files, the migration may take a few minutes
+- The backup is optional but highly recommended