docs: add API differences from upstream Java reference

[twcclegg]

Changes

• Adds docs/api-differences-from-java.md, a consolidated, scannable reference of places where this port's public API shape diverges from a literal Java-to-C# reading, or from what a C# developer would instinctively reach for. Each entry shows the Java shape, the C# shape, and why, and was verified against current source (several against an actual dotnet build).
• Moves the three existing "Known Issues" bullets from csharp/README.md (custom binary metadata format, binary geocoding/timezone/carrier maps, CharSequence → string) into the new page, and adds:
  • PhoneNumberOfflineGeocoder.GetDescriptionForNumber / PhoneNumberToCarrierMapper.GetNameForNumber take this library's own PhoneNumbers.Locale type, not System.Globalization.CultureInfo — confirmed a CultureInfo argument fails with CS1503.
  • PhoneNumbers.Extensions.PhoneNumber (the Extensions package's static TryParse/TryParseValid helper) shares its simple name with PhoneNumbers.PhoneNumber (the data type), producing a genuine CS0104 ambiguous-reference error when both namespaces are using'd together — confirmed by compiling a repro.
  • Public enums (PhoneNumberType, PhoneNumberFormat, ErrorType, MatchType, ValidationResult, Leniency, ShortNumberCost, CountryCodeSource) keep Java's SCREAMING_SNAKE_CASE member names rather than .NET PascalCase.
  • PhoneNumber's public properties look like ordinary C# auto-properties but have internal setters (it's a protobuf-style immutable message, same as Java) — an object initializer like new PhoneNumber { CountryCode = 1 } fails with CS0200; construction goes through PhoneNumberUtil.Parse or PhoneNumber.CreateBuilder()...Build().
• Updates csharp/README.md's "Known Issues" section to keep the original three bullets in place (no link rot for existing readers) and link out to the new page for the fuller reference.

Motivated by real mistakes made while exercising the library's public API as a consumer this session — the goal is to save the next contributor or consumer the same trial and error.

Test plan

• Verified every claimed compiler error (CS1503 for CultureInfo, CS0104 for the PhoneNumber naming collision, CS0200 for the PhoneNumber object initializer) by compiling a standalone repro project against this repo's PhoneNumbers/PhoneNumbers.Extensions projects.
• Verified all cited types/members/file paths against current source (Locale in PhoneNumberOfflineGeocoder.cs, enum definitions, Phonenumber.cs builder shape).
• Docs-only change — no .cs/.csproj/workflow files touched, so no build or test run is needed.

---

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 87.26%. Comparing base (0bf7478) to head (bd5b69b).

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #439   +/-   ##
=======================================
  Coverage   87.26%   87.26%           
=======================================
  Files          41       41           
  Lines        3831     3831           
  Branches      978      978           
=======================================
  Hits         3343     3343           
  Misses        284      284           
  Partials      204      204           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.