Add comprehensive documentation and usage instructions

- Added CLAUDE.md with detailed project documentation and roadmap
- Enhanced README.md with usage section for command line and GUI modes
- Updated with Claude Code credit
- Improved master_core.py with better song name handling and BPM display

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

CLAUDE.md

@@ -0,0 +1,132 @@
+# uj-mastering-master
+
+A custom mastering toolkit that provides metrics to evaluate audio masterings through visual analysis.
+
+## Current Implementation
+
+### Core Features
+- **Audio Analysis**: Uses librosa to analyze audio files (MP3/WAV support)
+- **Power Visualization**: Generates colorized power magnitude graphs over time
+- **Metadata Extraction**: Reads ID3 tags from MP3 files for better file identification
+- **GUI Foundation**: Basic PyQt5 drag-and-drop interface (work in progress)
+
+### Technical Stack
+- **Audio Processing**: librosa, numpy
+- **Visualization**: matplotlib with custom colormaps
+- **GUI Framework**: PyQt5 (drag-and-drop functionality)
+- **Metadata**: mutagen for MP3 tag reading
+
+### Key Components
+
+#### `master_core.py`
+- `AudioFile` class: Main audio processing class
+  - Loads audio files and extracts basic metrics (max/avg amplitude, BPM)
+  - `get_energy_levels_over_time()`: Calculates RMS power over rolling windows
+  - `plot_energy_levels_over_time()`: Creates colorized power graphs with automatic headroom detection
+- `analyze_track_librosa()`: Legacy analysis function (dBFS calculations)
+- File processing from `files.txt` configuration
+
+#### `main.py`
+- PyQt5 drag-and-drop interface
+- Currently displays file paths but doesn't integrate with analysis functions
+- Placeholder for GUI integration
+
+#### `files.txt`
+- Configuration file listing audio files to analyze
+- Supports comments (`;` and `#` prefixed lines)
+- Currently contains various music file paths
+
+### Current Analysis Features
+- **RMS Power Analysis**: 10-second rolling window with 2-second hops
+- **Adaptive Color Mapping**: Automatically adjusts scale based on detected headroom
+  - High dynamic range: 0-0.6 scale for loud masters
+  - Conservative mastering: 0-0.3 scale for quiet masters
+- **BPM Detection**: Automatic tempo analysis
+- **Metadata Display**: Artist and title from ID3 tags
+
+### Known Issues
+- GUI integration incomplete (drag-drop doesn't trigger analysis)
+- MP3 tag reading temporarily disabled in some parts
+- No interactive features yet implemented
+
+## Future Development Plans
+
+### Short-term Goals
+1. **Complete GUI Integration**
+   - Connect drag-drop functionality to analysis pipeline
+   - Real-time graph display in GUI window
+   - File browser for batch processing
+
+2. **Enhanced Metrics**
+   - Dynamic range measurement (DR meter)
+   - Peak-to-average ratio analysis
+   - Frequency spectrum analysis
+   - Loudness standards compliance (LUFS)
+
+3. **Interactive Features**
+   - Zoom/pan on power graphs
+   - Playback controls with visual cursor
+   - Export analysis results to CSV/JSON
+
+### Medium-term Goals
+1. **Advanced Analysis Tools**
+   - Spectral centroid and bandwidth analysis
+   - Stereo width measurements
+   - Transient detection and analysis
+   - Harmonic distortion detection
+
+2. **Comparison Features**
+   - Side-by-side track comparison
+   - Reference track overlay
+   - Mastering version A/B testing
+
+3. **Batch Processing**
+   - Folder-based analysis
+   - Automated report generation
+   - Progress tracking for large collections
+
+### Long-term Vision
+1. **VST Plugin Development**
+   - Real-time analysis during mixing/mastering
+   - Integration with DAWs
+   - Live feedback during production
+
+2. **Professional Features**
+   - EBU R128 compliance checking
+   - Custom target curves
+   - Professional reporting formats
+   - Multi-format export capabilities
+
+## Development Notes
+
+### Dependencies
+- librosa: Audio analysis and feature extraction
+- numpy: Numerical computations
+- matplotlib: Plotting and visualization
+- mutagen: Audio metadata extraction
+- PyQt5: GUI framework
+
+### Architecture Considerations
+- Current code mixes analysis and visualization - consider separation
+- File path handling needs improvement for cross-platform compatibility
+- Error handling should be enhanced for production use
+- Consider moving from PyQt5 to PyQt6 or PySide for better licensing
+
+### Testing Requirements
+- Unit tests for audio analysis functions
+- GUI component testing
+- File format compatibility testing
+- Performance testing with large audio files
+
+## Usage
+
+### Current Usage
+1. Add audio file paths to `files.txt`
+2. Run `python master_core.py` for batch analysis
+3. Run `python main.py` for GUI (incomplete)
+
+### Planned Usage
+1. Drag and drop audio files into GUI
+2. Real-time analysis with interactive graphs
+3. Export reports and comparisons
+4. VST plugin for DAW integration