feat(docs): add comprehensive README for masterdata service

- Introduced detailed documentation for `masterdata` service, outlining purpose, architecture, and ÖTO rule compliance.
- Highlighted its hexagonal architecture and Gradle multi-module project structure.
- Documented key APIs, domain models (`LandDefinition`, `Altersklasse`, `Platz`), and testing practices using Testcontainers.
- Emphasized the service’s role as a central source of truth for ÖTO-conformant reference data.

Signed-off-by: Stefan Mogeritsch <stefan.mo.co@gmail.com>

backend/services/masterdata/README.md

@@ -0,0 +1,65 @@
+# 🧹 Masterdata Service
+
+Der **Masterdata Service** ist ein zentraler Bounded Context innerhalb der Meldestelle-Biest Architektur. Er dient als "
+Single Source of Truth" für alle statischen und semi-statischen Stammdaten, die für den Turnierbetrieb und die
+Verwaltung von Reitern, Pferden und Organisationen (Vereinen) notwendig sind.
+
+## 🎯 Zweck & Aufgaben
+
+Dieser Service stellt sicher, dass alle anderen Contexts (wie `registration-context` oder `actor-context`) auf
+konsistente und standardisierte Referenzdaten zugreifen können.
+
+**Hauptaufgaben:**
+
+* **Geografische Daten:** Verwaltung von Ländern (ISO-Codes), Bundesländern und deren OEPS-spezifischen Kürzeln.
+* **Sportliche Reglements:** Bereitstellung von Altersklassen (ÖTO-konform), Sparten und Lizenzstufen.
+* **Infrastruktur:** Verwaltung von Austragungsplätzen (Dimensionen, Bodenbeschaffenheit) innerhalb von Turnierstätten.
+* **Referenzdaten:** Zentrale Pflege von Enums und Konstanten (z.B. Turniertypen, Status-Codes).
+
+## 🏗️ Architektur & Modulstruktur
+
+Der Service folgt einer **Hexagonalen Architektur** und ist als Gradle Multi-Modul-Projekt innerhalb des Backends
+organisiert. Dies ermöglicht eine saubere Trennung zwischen Fachlogik und technischer Infrastruktur.
+
+| Modul                       | Beschreibung                                                                                                                                   |
+|-----------------------------|------------------------------------------------------------------------------------------------------------------------------------------------|
+| `masterdata-domain`         | **KMP-Modul.** Enthält die Domänenmodelle (`LandDefinition`, `Altersklasse`, etc.) und Repository-Interfaces. Keine Abhängigkeiten nach außen. |
+| `masterdata-common`         | Beinhaltet die fachliche Logik in Form von **Use-Cases** (Interaktoren).                                                                       |
+| `masterdata-api`            | Stellt die REST-Schnittstellen mittels **Ktor** bereit. Enthält Controller, DTO-Mapping und das Idempotency-Plugin.                            |
+| `masterdata-infrastructure` | Implementiert die Persistenzschicht mit **Exposed** (PostgreSQL) und bindet externe Dienste an.                                                |
+| `masterdata-service`        | Der **Spring Boot Host**, der alle Module zusammenführt, die Konfiguration verwaltet und den Service startet.                                  |
+
+## 🛠️ Wichtige Domänenmodelle (Auszug)
+
+* **`LandDefinition`:** ISO-3166 konforme Länderdaten inklusive EU/EWR-Status und Wappen-URLs.
+* **`Bundesland`:** Zuordnung zu Ländern, inklusive der für die OEPS-Satznummern relevanten Landes-Codes.
+* **`Altersklasse`:** Definitionen basierend auf dem Geburtsjahr, Geschlecht und der Sparte (ÖTO § 39).
+* **`Platz`:** Beschreibung von Austragungs- und Vorbereitungsplätzen für Turniere.
+
+## 🔌 Schnittstellen (API)
+
+Die APIs sind unter `/api/v1/masterdata/...` erreichbar.
+
+**Wichtige Endpunkte:**
+
+* `GET /countries`: Liste aller unterstützten Länder.
+* `GET /bundeslaender`: Regionale Gliederung (vorrangig Österreich).
+* `GET /altersklassen`: Abfrage der gültigen Klassen für einen Reiter in einer bestimmten Sparte.
+* `GET /plaetze`: Infrastruktur-Abfrage für Turnierplanung.
+
+## 🧪 Entwicklung & Tests
+
+* **Unit-Tests:** Befinden sich in den jeweiligen Modulen (v.a. `domain` und `common`).
+* **Integration-Tests:** Nutzen Testcontainers für die Datenbankvalidierung (in `infrastructure` und `service`).
+* **Idempotenz:** Der Service nutzt ein spezialisiertes `IdempotencyPlugin` in der API-Schicht, um doppelte
+  Schreiboperationen bei Netzwerkfehlern zu verhindern.
+
+## 📜 ÖTO-Konformität
+
+Sämtliche Stammdaten (insbesondere Altersklassen und Sparten) sind strikt nach dem **ÖTO (Österreichische
+Turnierordnung)** Regelwerk modelliert. Änderungen am Regelwerk müssen hier zentral eingepflegt werden, damit sie
+systemweit (z.B. in der Nennungsprüfung) wirksam werden.
+
+---
+> 🧹 **Curator-Hinweis:** Diese Dokumentation wird laufend aktualisiert. Änderungen an der Domänenstruktur müssen in der
+`MASTER_ROADMAP` reflektiert werden.

docs/99_Journal/2026-03-30_Session_Log_Masterdata_README.md

@@ -0,0 +1,51 @@
+---
+type: Journal
+status: COMPLETED
+owner: Curator
+last_update: 2026-03-30
+---
+
+# Session Log: Stammdaten-Service Dokumentation (README)
+
+🧹 **[Curator]** | 30. März 2026
+
+## Kontext
+
+Der `masterdata` Service im Backend ist ein kritischer Bounded Context für die Bereitstellung von ÖTO-konformen
+Stammdaten. Bisher fehlte eine zentrale README-Datei, die den Zweck, die hexagonale Modulstruktur und die fachliche
+Bedeutung (ÖTO) für Entwickler schnell erfassbar macht.
+
+## Erledigte Aufgaben
+
+### 1. ✅ Analyse der Service-Struktur
+
+- Untersuchung der 5 Teilmodule: `masterdata-api`, `masterdata-common`, `masterdata-domain`, `masterdata-infrastructure`
+  und `masterdata-service`.
+- Identifikation der wichtigsten Domänenmodelle (`LandDefinition`, `Altersklasse`, `Platz`).
+- Prüfung der API-Endpunkte und der Persistenz-Implementierung (Exposed).
+
+### 2. ✅ Erstellung der README.md
+
+- Dokumentation des Services in deutscher Sprache in `backend/services/masterdata/README.md`.
+- Detaillierte Beschreibung der Modulverantwortlichkeiten.
+- Hervorhebung der **ÖTO-Konformität** als fachliche Basis.
+- Dokumentation technischer Besonderheiten wie des `IdempotencyPlugin`.
+
+## Technische Details & Architektur
+
+- **Architektur:** Hexagonale Architektur (Ports & Adapters).
+- **Technologien:** Kotlin (KMP für Domain), Ktor (API), Exposed (SQL), Spring Boot (Host).
+- **Fachlicher Fokus:** ÖTO § 39 (Altersklassen) und Geografische Referenzdaten (OEPS-Kürzel).
+
+## Nächste Schritte
+
+- Synchronisation der Dokumentation mit dem `actor-context`, da dieser stark von den Stammdaten abhängt.
+- Regelmäßige Aktualisierung der `MASTER_ROADMAP` bei Erweiterung der Stammdaten-Typen.
+
+---
+
+## Referenzen
+
+- `MASTER_ROADMAP.md` (Phase 4: MVP-Implementierung)
+- ÖTO (Österreichische Turnierordnung)
+- ADR-0016 (API-Design & ACL)