docs: polish README for mainnet readiness (#126)

- Add badges (crates.io, docs.rs, CI, license)
- Improve formatting with tables
- Better code examples with avoid/instead pattern
- Cleaner section organization

Closes ENG-2065

Author: init4samwise